# 离线声纹Linux SDK
# 功能简介
声纹识别SDK基于科大讯飞MorfeiCore AIOT架构构建，通过说话人特定的语音片段，利用声纹识别技术，对说话人的身份进行判断。本文主要描述声纹识别相关接口及调用流程，用于指导开发人员快速进行声纹识别集成。
# 名词解释
| 名词 | 说明 |
|---|---|
| 声纹识别 | 根据语音中反映的说话人生理和行为特征，自动识别说话人身份的生物识别技术。 |
| VPR | Voiceprint Recognition |
# 授权说明
授权方式目前只支持云端授权方式。
云端授权方式：使用云端授权方式，设备需要具备联网能力。在启动声纹识别服务前设备需要联网，否则SDK无法通过网络获取授权，SDK能力将无法使用。在购买SDK开发包后，科大讯飞为每台设备分配productid （每个产品唯一）和deviceid（每台设备唯一），开发者在启动声纹识别服务时通过相应接口将productid和deviceid传入SDK。
# 相关约定说明
文档中使用的符号约定：
| 符号 | 含义 |
|---|---|
| [in] | 表明该参数是调用时赋值的参数——输入参数 |
| [out] | 该参数在函数返回时被赋值——输出参数 |
| [in/out] | 该参数在函数调用时作为输入、函数返回时作为输出参数 |
# 声纹唤醒SDK接口说明
# 接口调用流程
声纹识别接口基本功能使用，调用流程包括以下几个步骤（图2-1）：
（1） MorfeiCore服务初始化
（2） 声纹引擎初始化
（3） 声纹资源加载
（4） 引擎参数设置
（5） 声纹信息注册
（6） 声纹实例创建
（7） VPR回调函数注册
（8） 启动声纹实例
（9） 写入音频，回调抛出识别结果
（10） 停止声纹实例
（11） 销毁声纹实例
（12） 卸载声纹资源
（13） 声纹引擎逆初始化
（14） MorfeiCore 服务逆初始化
# MorfeiCore 接口函数列表
| 函数名称 | 功能简介 |
|---|---|
| morfeicore_start | 初始化MorfeiCore 服务 |
| morfeicore_stop | 逆初始化MorfeiCore 服务 |
| morfeicore_getversion | 获取MorfeiCore版本号 |
# VPR接口函数列表
| 函数名称 | 功能简介 |
|---|---|
| VPRInit | 初始化VPR引擎 |
| VPRUninit | 逆初始化VPR引擎 |
| VPRGetVersion | 获取VPR引擎版本号 |
| VPRLoadResource | 加载VPR资源 |
| VPRUnloadResource | 删除VPR资源 |
| VPRRegister | 注册VPR资源 |
| VPRCreateInst | 创建VPR引擎实例 |
| VPRDestoryInst | 销毁VPR引擎实例 |
| VPRSetListener | 设置VPR回调接口 |
| VPRGetParam | 获取VPR实例参数 |
| VPRSetParam | 设置VPR实例参数 |
| VPRStartInst | 启动一个VPR实例 |
| VPRWriteAudio | 写入音频 |
| VPRStopInst | 停止一个VPR实例 |
| VPRResetInst | 重置一个VPR实例 |
# 返回值说明
对于开发接口，如果调用成功，返回值为int型的接口都会返回0，否则返回错误代码，错误代码参见aiot_errors.h。
# MorfeiCore函数调用
# morfeicore_start
函数原型
int morfeicore_start(const char *params, morfeicore_status_cb_t status_cb, void *user_data);
功能说明
初始化MorfeiCore服务，若同时使用基于MorfeiCore服务的其他SDK，则此函数只需调用一次。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| params[in] | 参数字符串 |
| status_cb[in] | 回调函数 |
| user_data[in] | 用户数据 |
status回调接口声明
typedef int ( *morfeicore_status_cb_t)( int type, int status, int param1, const void *param2, void *user_data);
回调参数说明
| 参数名 | 参数解释 |
|---|---|
| type[out] | 数据类型 |
| status[out] | 状态信息 |
| param1[out] | 保留参数 |
| param2[out] | 保留参数 |
| user_data[out] | 用户数据 |
# morfeicore_stop
函数原型
int morfeicore_stop(void);
功能说明
逆初始化MorfeiCore服务。
返回值
如果函数调用成功返回0，失败返回错误码。
# morfeicore_ getversion
函数原型
const char* morfeicore_getversion(void);
功能说明
获取MorFeiCore 版本号。
返回值
如果函数调用成功返回引擎版本号。
# VPR函数调用
# VPRInit
函数原型
int VPRInit(struct aiotOS * param, void* reserved);
功能说明
初始化VPR引擎。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| param[in] | 保留使用的结构体参数 |
| reserved[in] | 接口保留参数 |
# VPRUnInit
函数原型
int VPRUninit(void* reserved);
功能说明
逆初始化VPR引擎。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| reserved[in] | 接口保留参数 |
# VPRGetVersion
函数原型
char* VPRGetVersion(void);
功能说明
获取VPR引擎版本号。
返回值
如果函数调用成功返回引擎版本号，例如：2.0.1001。
# VPRLoadResource
函数原型
int VPRLoadResource(const char* res, int ressize, void* reserved);
功能说明
加载VPR资源。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| res[in] | 加载资源的首地址 |
| resize[in] | 资源长度 |
| reserved[in] | 接口保留参数 |
# VPRUnloadResource
函数原型
int VPRUnloadResource(int restype, int resid);
功能说明
卸载VPR资源。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| restype[in] | 资源类型 |
| resid[in] | 资源ID |
# VPRRegister
函数原型
int VPRRegister(const char* srcres, int srcressize, const char* registerbuf, int registertype, int registerid, int registersize, char* targetres, int* targetsize);
功能说明
注册VPR资源。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| srcres[in] | 原始资源地址 |
| srcressize[in] | 原始资源大小 |
| registerbuf[in] | 注册音频数据地址（16k、16bit、单通道、pcm音频） |
| registertype[in] | 注册资源类型 |
| registered[in] | 注册资源ID |
| registersize[in] | 注册资源大小 |
| targetres[in] | 存储资源地址 |
| targetsize[in/out] | 存储资源大小 |
# VPRCreateInst
函数原型
int VPRCreateInst(VPR_HANDLE* pvprinst);
功能说明
创建VPR引擎实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| pvprinst[out] | 实例对象句柄二级指针 |
# VPRDestoryInst
函数原型
int VPRDestoryInst(VPR_HANDLE vprinst);
功能说明
销毁VPR引擎实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
# VPRSetListener
函数原型
int VPRSetListener(VPR_HANDLE vprinst, const int cbtype, const void* listener, void* userdata);
功能说明
设置VPR回调接口。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
| cbtype[in] | 参数类型：VPR_PARAM_RESULTCALLBACK 注册声纹回调函数 参数类型：IVW_PARAM_WAKEUPCALLBACK 注册唤醒回调函数 |
| listener[in] | 回调函数指针 |
| userdata[in] | 用户数据 |
声纹信息回调接口声明
typedef int (*VprCallBack)(void *pUserParam, const char* pVprParam);
回调参数说明
| 参数名 | 参数解释 |
|---|---|
| pUserParam[out] | 用户数据 |
| pVprParam[out] | 声纹信息 |
唤醒信息回调接口声明
typedef int (*IvwCallBack)(void *pUserParam, const char* pVprParam);
回调参数说明
| 参数名 | 参数解释 |
|---|---|
| pUserParam[out] | 用户数据 |
| pVprParam[out] | 唤醒信息 |
# VPRGetParam
函数原型
int VPRGetParam(VPR_HANDLE vprinst, int paramtype, void* paramvalue, int* paramsize);
功能说明
获取VPR实例参数。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
| paramtype[in] | 参数类型： VPR_PARAM_ENGINE_MODE 说 明 ：获取引擎工作模式 |
| paramvalue[out] | 参数值 |
| paramsize[in/out] | 参数长度 |
# VPRSetParam
函数原型
int VPRSetParam(VPR_HANDLE vprinst, int paramtype, void* paramvalue, int paramsize);
功能说明
设置VPR实例参数。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
| paramtype[in] | 参数类型： VPR_PARAM_ENGINE_MODE 说 明 ： 设置引擎模式 |
| paramvalue[in] | 参数值 |
| paramsize[in] | 参数长度 |
# VPRStartInst
函数原型
int VPRStartInst(VPR_HANDLE vprinst);
功能说明
启动一个声纹实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
# VPRWriteAudio
函数原型
int VPRWriteAudio(VPR_HANDLE vprinst, const char* buf, int bufsize, int writestatus);
功能说明
写入音频。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
| buf[in] | 音频数据地址（16k、16bit、单通道、pcm音频） |
| bufsize[in] | 传入音频长度，字节为单位 |
| writestatus[in] | 当前数据状态标志 |
# VPRStopInst
函数原型
int VPRStopInst(VPR_HANDLE vprinst);
功能说明
停止一个声纹实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
# VPRResetInst
函数原型
int VPRResetInst(VPR_HANDLE vprinst);
功能说明
重置一个声纹实例。
返回值
如果函数调用成功返回0，失败返回错误码。
参数说明
| 参数名 | 参数解释 |
|---|---|
| vprinst[in] | 实例对象句柄指针 |
